Introduction

A design document is a way for you to communicate to others what your design decisions are and why your decisions are good decisions.

Many software projects span many years and it is natural for team members to leave and others arrive. Design documentation is a useful tool for bringing new members up-to-speed quickly. A good design doc provides a high-level perspective of the requirements, domain and architecture. And as appropriate selected sub-systems are described in detail.

Learning Outcomes

• Create a document that provides a high-level view of a system's architecture and design.
• Create simple and effective system and subsystem models.

Study Resources

For your study of this topic, use some of these resources.

Web Articles and Blogs

There are many software architectures; some are more complex than others. Similarly there are many forms of software design documentation; some are much more complex than others. We encourage light-weight documentation that favors quality over quantity. Excerpts of Scott Hackett provides a simple description of design documentation and Martin Fowler provides a humorous encounter with a team's impressive documentation.

• Scott Hackett: How to Write an Effective Design Document
• Martin Fowler: The Almighty Thud

The Agile Modeling website is full of good content for modeling in an agile environment. This webpage on best practices is a good read.

• Best Practices for Agile/Lean Documentation

Many in Agile circles say that code should be the design documentation and it is certainly true that good design and clear code communication can enhance a developer's understanding of the system. Here's what Martin Fowler has to say about that:

• Martin Fowler: CodeAsDocumentation

Finally, software maven Joel Spolsky provides his own take on design document (what he calls "Functional Spec"):

• Painless Functional Specs: Part 1: Why Bother?
• Painless Functional Specs: Part 2: What's a Spec?
• Painless Functional Specs: Part 3: But... How?
• Painless Functional Specs: Part 4: Tips

Wikipedia

• Software documentation
• Software design description
• High-level design
• Software architecture description

Class Lecture

• Design Documentation

Exercises

After-Class Exercises

• Design documentation - team (2 exercise points)
  • As a team, perform the design documentation exercise to expand the documentation area in your repository. Submit the PDF file of the initial design document before the time indicated on the schedule for your section.
  • Check the Resources page for tools to edit markdown files.
  • Split up the work for writing the design documentation due in your Sprint 2 submission.

Project Activities

• The Definition of Done checklist in the STORY template card in your Trello planning board includes a checklist item for "design documentation updated". From this point, when you implement a story you will include updating the design documenation as part of your sprint process.